/*
-------------------------------------------------------------------
BIE is Copyright 2001-2003 Brunswick Corp.
-------------------------------------------------------------------
Please read the legal notices (docs/legal.txt) and the license
(docs/bie_license.txt) that came with this distribution before using
this software.
-------------------------------------------------------------------
*/
/*
 * Client.java
 *
 * Created on December 13, 2002, 4:14 PM
 */

package com.webdeninteractive.sbie;

import com.webdeninteractive.sbie.config.SystemConfig;
import com.webdeninteractive.sbie.exception.ComponentException;

/**
 *  SBIE component which runs services via a certain transport layer.
 *  <p>
 *  The services which this client should run, and the parameters
 *  controlling how and when to run them, are given by this client's
 *  configuration.
 *  <p>
 *  Typically, a Client implemetation will run a list of services
 *  (with <code>runService</code>) at a defined intervals, until it is
 *  halted.
 *  <p>
 *  A Client runs in its own thread.
 *
 * @author  bmadigan
 * @version $Id: Client.java,v 1.1.1.1 2003/05/20 16:56:49 gdf Exp $ 
 */
public interface Client extends Runnable {

    /** Signal this client to stop running.
     *  The client will clean up any loose ends and exit.
     */
    public void halt();

    /** Each client has a set of configured services=(name, interval)
     *  The client starts Timers for each service, with the given interval
     *  (if the interval is -1 or something, run it once only)
     */

    /** Run a given named Service, according to its configuration.
     *  If the service has a defined interval, a new timed service will be
     *  started for it, otherwise it will be run a single time.
     *  Does nothing if no service of the given name is configured 
     *  for this Client.
     * @see #runService
     * @see #startTimedService
     * @param serviceName Name of the Service to start/run.
     */
    public void startService( String serviceName );

    public void stopService( String serviceName );

    /** Run the given named Service once.
     *  This creates a new Service implementation, and runs it.
     *  @param serviceName The name of the Service to run.
     *  @throws ComponentException if the Service cannot be started.
     *  @throws IllegalStateException if this Client has been halted.
     */
    public void runService( String serviceName )
        throws ComponentException, IllegalStateException;

    /** Create a Timer thread to run the named Service at intervals.
     *  This creates a Timer scheduled to run the given Service
     *  each given time step.  The Timer can be stopped later with 
     *  stopTimedService().
     *  @param serviceName The name of the Service to run.
     *  @param intervalMS How often to run the Service, in milliseconds.
     *  @throws ComponentException if the Service cannot be started.
     *  @throws IllegalStateException if this Client has been halted.
     */
    public void startTimedService( String serviceName, long intervalMS )
        throws ComponentException, IllegalStateException;

    /** Cancel a timed service.
     *  Stop the periodic execution of the given service, 
     *  which was previously created with startTimedService().
     *  It is safe to call this for a serviceName which is not 
     *  currently running (or does not exist).
     *  @param serviceName The name of the Service to stop.
     */
    public void stopTimedService( String serviceName );

    /** Store a reference to the RemoteSystem which created this Client.
     *  The client needs to keep a reference to its parent system,
     *  in case services that it runs need to start or stop clients.
     *  @param system The RemoteSystem which started this Client.
     */
    public void setParentSystem( RemoteSystem system );

    /** Get a reference to the RemoteSystem which started this Client. */
    public RemoteSystem getParentSystem();

    /** Associate a configuration object with this Client. */
    public void setConfiguration( SystemConfig config );
    
    /** Return the configuration object associated with this Client. */
    public SystemConfig getConfiguration();

    /** Assign a name to this Client, so that it knows how to look up
     *  configuration information.
     */
    public void setName(String clientName);

    /** Returns the name of this Client. */
    public String getName();

}
